Language/OS - Multiplatform Resource Library/LANGUAGE OS.iso/lisp/wgdb-42.lha/wgdb-4.2/gdb/gdb.info-3

Text File | 1992-09-11 | 49KB | 1,307 lines

Info file gdb.info, produced by Makeinfo, -*- Text -*- from input
file gdb-all.texi.

   This file documents the GNU debugger GDB.

   Copyright (C) 1988, 1989, 1990, 1991 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of
this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this
manual under the conditions for verbatim copying, provided also that
the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for
modified versions, except that the section entitled "GNU General
Public License" may be included in a translation approved by the
Free Software Foundation instead of in the original English.


File: gdb.info,  Node: List,  Next: Search,  Prev: Source,  Up: Source

Printing Source Lines
=====================

   To print lines from a source file, use the `list' command
(abbreviated `l').  There are several ways to specify what part of
the file you want to print.

   Here are the forms of the `list' command most commonly used:

`list LINENUM'
     Print lines centered around line number LINENUM in the current
     source file.

`list FUNCTION'
     Print lines centered around the beginning of function FUNCTION.

`list'
     Print more lines.  If the last lines printed were printed with a
     `list' command, this prints lines following the last lines
     printed; however, if the last line printed was a solitary line
     printed as part of displaying a stack frame (*note Stack::.),
     this prints lines centered around that line.

`list -'
     Print lines just before the lines last printed.

   By default, GDB prints ten source lines with any of these forms of
the `list' command.  You can change this using `set listsize':

`set listsize COUNT'
     Make the `list' command display COUNT source lines (unless the
     `list' argument explicitly specifies some other number).

`show listsize'
     Display the number of lines that `list' will currently display
     by default.

   Repeating a `list' command with RET discards the argument, so it
is equivalent to typing just `list'.  This is more useful than
listing the same lines again.  An exception is made for an argument
of
`-'; that argument is preserved in repetition so that each
repetition moves up in the source file.

   In general, the `list' command expects you to supply zero, one or
two "linespecs".  Linespecs specify source lines; there are several
ways of writing them but the effect is always to specify some source
line.  Here is a complete description of the possible arguments for
`list':

`list LINESPEC'
     Print lines centered around the line specified by LINESPEC.

`list FIRST,LAST'
     Print lines from FIRST to LAST.  Both arguments are linespecs.

`list ,LAST'
     Print lines ending with LAST.

`list FIRST,'
     Print lines starting with FIRST.

`list +'
     Print lines just after the lines last printed.

`list -'
     Print lines just before the lines last printed.

`list'
     As described in the preceding table.

   Here are the ways of specifying a single source line--all the
kinds of linespec.

`NUMBER'
     Specifies line NUMBER of the current source file.  When a `list'
     command has two linespecs, this refers to the same source file
     as the first linespec.

`+OFFSET'
     Specifies the line OFFSET lines after the last line printed.
     When used as the second linespec in a `list' command that has
     two, this specifies the line OFFSET lines down from the first
     linespec.

`-OFFSET'
     Specifies the line OFFSET lines before the last line printed.

`FILENAME:NUMBER'
     Specifies line NUMBER in the source file FILENAME.

`FUNCTION'
     Specifies the line of the open-brace that begins the body of the
     function FUNCTION.

`FILENAME:FUNCTION'
     Specifies the line of the open-brace that begins the body of the
     function FUNCTION in the file FILENAME.  You only need the file
     name with a function name to avoid ambiguity when there are
     identically named functions in different source files.

`*ADDRESS'
     Specifies the line containing the program address ADDRESS.
     ADDRESS may be any expression.


File: gdb.info,  Node: Search,  Next: Source Path,  Prev: List,  Up: Source

Searching Source Files
======================

   There are two commands for searching through the current source
file for a regular expression.

`forward-search REGEXP'
`search REGEXP'
     The command `forward-search REGEXP' checks each line, starting
     with the one following the last line listed, for a match for
     REGEXP.  It lists the line that is found.  You can abbreviate
     the command name as `fo'.  The synonym `search REGEXP' is also
     supported.

`reverse-search REGEXP'
     The command `reverse-search REGEXP' checks each line, starting
     with the one before the last line listed and going backward,
     for a match for REGEXP.  It lists the line that is found.  You
     can abbreviate this command as `rev'.


File: gdb.info,  Node: Source Path,  Next: Machine Code,  Prev: Search,  Up: Source

Specifying Source Directories
=============================

   Executable programs sometimes do not record the directories of the
source files from which they were compiled, just the names.  Even
when they do, the directories could be moved between the compilation
and your debugging session.  GDB has a list of directories to search
for source files; this is called the "source path".  Each time GDB
wants a source file, it tries all the directories in the list, in
the order they are present in the list, until it finds a file with
the desired name.  Note that the executable search path is *not*
used for this purpose.  Neither is the current working directory,
unless it happens to be in the source path.

   If GDB can't find a source file in the source path, and the object
program records a directory, GDB tries that directory too.  If the
source path is empty, and there is no record of the compilation
directory, GDB will, as a last resort, look in the current directory.

   Whenever you reset or rearrange the source path, GDB will clear
out any information it has cached about where source files are
found, where each line is in the file, etc.

   When you start GDB, its source path is empty.  To add other
directories, use the `directory' command.

`directory DIRNAME ...'
     Add directory DIRNAME to the front of the source path.  Several
     directory names may be given to this command, separated by `:'
     or whitespace.  You may specify a directory that is already in
     the source path; this moves it forward, so it will be searched
     sooner.

     You can use the string `$cdir' to refer to the compilation
     directory (if one is recorded), and `$cwd' to refer to the
     current working directory.  `$cwd' is not the same as `.'--the
     former tracks the current working directory as it changes
     during your GDB session, while the latter is immediately
     expanded to the current directory at the time you add an entry
     to the source path.

`directory'
     Reset the source path to empty again.  This requires confirmation.

`show directories'
     Print the source path: show which directories it contains.

   If your source path is cluttered with directories that are no
longer
of interest, GDB may sometimes cause confusion by finding the wrong
versions of source.  You can correct the situation as follows:

  1. Use `directory' with no argument to reset the source path to
     empty.

  2. Use `directory' with suitable arguments to reinstall the
     directories you want in the source path.  You can add all the
     directories in one command.


File: gdb.info,  Node: Machine Code,  Prev: Source Path,  Up: Source

Source and Machine Code
=======================

   You can use the command `info line' to map source lines to program
addresses
(and viceversa), and the command `disassemble' to display a range of
addresses as machine instructions.

`info line LINESPEC'
     Print the starting and ending addresses of the compiled code for
     source line LINESPEC.  You can specify source lines in any of
     the ways understood by the `list' command (*note List::.).

   For example, we can use `info line' to inquire on where the object
code for the first line of function `m4_changequote' lies:

     (gdb) info line m4_changecom
     Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.

We can also inquire (using `*ADDR' as the form for LINESPEC) what
source line covers a particular address:

     (gdb) info line *0x63ff
     Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.

   After `info line', the default address for the `x' command is
changed to the starting address of the line, so that `x/i' is
sufficient to begin examining the machine code (*note Memory::.).
Also, this address is saved as the value of the convenience variable
`$_' (*note Convenience Vars::.).

`disassemble'
     This specialized command is provided to dump a range of memory
     as machine instructions.  The default memory range is the
     function surrounding the program counter of the selected frame.
     A single argument to this command is a program counter value;
     the function surrounding this value will be dumped.  Two
     arguments (separated by one or more spaces) specify a range of
     addresses (first inclusive, second exclusive) to be dumped.

   We can use `disassemble' to inspect the object code range shown in
the last `info line' example:

     (gdb) disas 0x63e4 0x6404
     Dump of assembler code from 0x63e4 to 0x6404:
     0x63e4 builtin_init+5340:     ble 0x63f8 builtin_init+5360
     0x63e8 builtin_init+5344:     sethi %hi(0x4c00), %o0
     0x63ec builtin_init+5348:     ld [%i1+4], %o0
     0x63f0 builtin_init+5352:     b 0x63fc builtin_init+5364
     0x63f4 builtin_init+5356:     ld [%o0+4], %o0
     0x63f8 builtin_init+5360:     or %o0, 0x1a4, %o0
     0x63fc builtin_init+5364:     call 0x9288 path_search
     0x6400 builtin_init+5368:     nop
     End of assembler dump.
     (gdb)


File: gdb.info,  Node: Data,  Next: Languages,  Prev: Source,  Up: Top

Examining Data
**************

   The usual way to examine data in your program is with the `print'
command (abbreviated `p'), or its synonym `inspect'.  It evaluates
and prints the value of an expression of the language your program
is written in (*note Languages::.).

`print EXP'
`print /F EXP'
     EXP is an expression (in the source language).  By default the
     value of EXP is printed in a format appropriate to its data
     type; you can choose a different format by specifying `/F',
     where F is a letter specifying the format; *note Output
     formats::..

`print'
`print /F'
     If you omit EXP, GDB displays the last value again (from the
     "value history"; *note Value History::.).  This allows you to
     conveniently inspect the same value in an alternative format.

   A more low-level way of examining data is with the `x' command.
It examines data in memory at a specified address and prints it in a
specified format.  *Note Memory::.

   If you're interested in information about types, or about how the
fields of a struct or class are declared, use the `ptype EXP'
command rather than `print'. *Note Symbols::.

* Menu:

* Expressions::                 Expressions
* Variables::                   Program Variables
* Arrays::                      Artificial Arrays
* Output formats::              Output formats
* Memory::                      Examining Memory
* Auto Display::                Automatic Display
* Print Settings::              Print Settings
* Value History::               Value History
* Convenience Vars::            Convenience Variables
* Registers::                   Registers
* Floating Point Hardware::     Floating Point Hardware


File: gdb.info,  Node: Expressions,  Next: Variables,  Prev: Data,  Up: Data

Expressions
===========

   `print' and many other GDB commands accept an expression and
compute its value.  Any kind of constant, variable or operator
defined by the programming language you are using is legal in an
expression in GDB.  This includes conditional expressions, function
calls, casts and string constants.  It unfortunately does not
include symbols defined by preprocessor `#define' commands.

   Because C is so widespread, most of the expressions shown in
examples in this manual are in C.  *Note Using GDB with Different
Languages: Languages, for information on how to use expressions in
other languages.

   In this section, we discuss operators that you can use in GDB
expressions regardless of your programming language.

   Casts are supported in all languages, not just in C, because it is
so useful to cast a number into a pointer so as to examine a
structure at that address in memory.

   GDB supports these operators in addition to those of programming
languages:

`@'
     `@' is a binary operator for treating parts of memory as arrays.
     *Note Arrays::, for more information.

`::'
     `::' allows you to specify a variable in terms of the file or
     function where it is defined.  *Note Variables::.

`{TYPE} ADDR'
     Refers to an object of type TYPE stored at address ADDR in
     memory.  ADDR may be any expression whose value is an integer
     or pointer (but parentheses are required around binary
     operators, just as in a cast).  This construct is allowed
     regardless of what kind of data is normally supposed to reside
     at ADDR.


File: gdb.info,  Node: Variables,  Next: Arrays,  Prev: Expressions,  Up: Data

Program Variables
=================

   The most common kind of expression to use is the name of a
variable in your program.

   Variables in expressions are understood in the selected stack
frame (*note Selection::.); they must either be global (or static)
or be visible according to the scope rules of the programming
language from the point of execution in that frame.  This means that
in the function

     foo (a)
          int a;
     {
       bar (a);
       {
         int b = test ();
         bar (b);
       }
     }

the variable `a' is usable whenever the program is executing within
the function `foo', but the variable `b' is visible only while the
program is executing inside the block in which `b' is declared.

   There is an exception: you can refer to a variable or function
whose scope is a single source file even if the current execution
point is not in this file.  But it is possible to have more than one
such variable or function with the same name (in different source
files).  If that happens, referring to that name has unpredictable
effects.  If you wish, you can specify a variable in a particular
file, using the colon-colon notation:

     FILE::VARIABLE

Here FILE is the name of the source file whose variable you want.

   This use of `::' is very rarely in conflict with the very similar
use of the same notation in C++.  GDB also supports use of the C++
scope resolution operator in GDB expressions.

     *Warning:* Occasionally, a local variable may appear to have the
     wrong value at certain points in a function--just after entry
     to the function, and just before exit.  You may see this
     problem when you're stepping by machine instructions.  This is
     because on most machines, it takes more than one instruction to
     set up a stack frame (including local variable definitions); if
     you're stepping by machine instructions, variables may appear
     to have the wrong values until the stack frame is completely

     built.  On function exit, it usually also takes more than one
     machine instruction to destroy a stack frame; after you begin
     stepping through that group of instructions, local variable
     definitions may be gone.


File: gdb.info,  Node: Arrays,  Next: Output formats,  Prev: Variables,  Up: Data

Artificial Arrays
=================

   It is often useful to print out several successive objects of the
same type in memory; a section of an array, or an array of
dynamically determined size for which only a pointer exists in the
program.

   This can be done by constructing an "artificial array" with the
binary operator `@'.  The left operand of `@' should be the first
element of the desired array, as an individual object.  The right
operand
should be the desired length of the array.  The result is an array
value whose elements are all of the type of the left argument.  The
first element is actually the left argument; the second element
comes from bytes of memory immediately following those that hold the
first element, and so on.  Here is an example.  If a program says

     int *array = (int *) malloc (len * sizeof (int));

you can print the contents of `array' with

     p *array@len

   The left operand of `@' must reside in memory.  Array values made
with `@' in this way behave just like other arrays in terms of
subscripting, and are coerced to pointers when used in expressions.
Artificial arrays most often appear in expressions via the value
history (*note Value History::.), after printing one out.)

   Sometimes the artificial array mechanism isn't quite enough; in
moderately complex data structures, the elements of interest may not
actually be adjacent--for example, if you're interested in the
values of pointers in an array.  One useful work-around in this
situation is to use a convenience variable (*note Convenience
Vars::.) as a counter in an expression that prints the first
interesting value, and then repeat that expression via RET.  For
instance, suppose you have an array `dtab' of pointers to
structures, and you're interested in the values of a field `fv' in
each structure.  Here's an example of what you might type:

     set $i = 0
     p dtab[$i++]->fv
     RET
     RET
     ...


File: gdb.info,  Node: Output formats,  Next: Memory,  Prev: Arrays,  Up: Data

Output formats
==============

   By default, GDB prints a value according to its data type.
Sometimes this is not what you want.  For example, you might want to
print a number in hex, or a pointer in decimal.  Or you might want
to view data in memory at a certain address as a character string or
as an instruction.  To do these things, specify an "output format"
when you print a value.

   The simplest use of output formats is to say how to print a value
already computed.  This is done by starting the arguments of the
`print' command with a slash and a format letter.  The format
letters supported are:

`x'
     Regard the bits of the value as an integer, and print the
     integer in hexadecimal.

`d'
     Print as integer in signed decimal.

`u'
     Print as integer in unsigned decimal.

`o'
     Print as integer in octal.

`t'
     Print as integer in binary.  The letter `t' stands for "two".

`a'
     Print as an address, both absolute in hex and as an offset from
     the nearest preceding symbol.  This format can be used to
     discover where (in what function) an unknown address is located:

          (gdb) p/a 0x54320
          $3 = 0x54320 <_initialize_vx+396>

`c'
     Regard as an integer and print it as a character constant.

`f'
     Regard the bits of the value as a floating point number and
     print
     using typical floating point syntax.

   For example, to print the program counter in hex (*note
Registers::.), type

     p/x $pc

Note that no space is required before the slash; this is because
command names in GDB cannot contain a slash.

   To reprint the last value in the value history with a different
format, you can use the `print' command with just a format and no
expression.  For example, `p/x' reprints the last value in hex.


File: gdb.info,  Node: Memory,  Next: Auto Display,  Prev: Output formats,  Up: Data

Examining Memory
================

`x/NFU ADDR'
`x ADDR'
`x'
     You can use the command `x' (for `examine') to examine memory in
     any of several formats, independently of your program's data
     types.  N, F, and U are all optional parameters to specify how
     much memory to display, and how to format it; ADDR is an
     expression giving the address where you want to start
     displaying memory.  If you use defaults for NFU, you need not
     type the slash `/'.  Several commands set convenient defaults
     for ADDR.

   N, the repeat count, is a decimal integer; the default is 1.  It
specifies how much memory (counting by units U) to display.

   F, the display format, is one of the formats used by `print', or
`s' (null-terminated string) or `i' (machine instruction).  The
default is `x' (hexadecimal) initially, or the format from the last
time you used either `x' or `print'.

   U, the unit size, is any of

`b'
     Bytes.

`h'
     Halfwords (two bytes).

`w'
     Words (four bytes).  This is the initial default.

`g'
     Giant words (eight bytes).

Each time you specify a unit size with `x', that size becomes the
default unit the next time you use `x'.  (For the `s' and `i'
formats, the unit size is ignored and is normally not written.)

   ADDR is the address where you want GDB to begin displaying memory.
The expression need not have a pointer value (though it may); it is
always interpreted as an integer address of a byte of memory.  *Note
Expressions:: for more information on expressions.  The default for
ADDR is usually just after the last address examined--but several
other commands also set the default address: `info breakpoints' (to
the address of the last breakpoint listed), `info line' (to the
starting address of a line), and `print' (if you use it to display a
value from memory).

   For example, `x/3uh 0x54320' is a request to display three
halfwords (`h') of memory, formatted as unsigned decimal integers
(`u'), starting at address `0x54320'.  `x/4xw $sp' prints the four
words (`w') of memory above the stack pointer (here, `$sp'; *note
Registers::.) in hexadecimal (`x').

   Since the letters indicating unit sizes are all distinct from the
letters specifying output formats, you don't have to remember
whether unit size or format comes first; either order will work.
The output specifications `4xw' and `4wx' mean exactly the same thing.
(However, the count N must come first; `wx4' will not work.)

   Even though the unit size U is ignored for the formats `s' and
`i', you might still want to use a count N; for example, `3i'
specifies that you want to see three machine instructions, including
any operands.  The command `disassemble' gives an alternative way of
inspecting
machine instructions; *note Machine Code::..

   All the defaults for the arguments to `x' are designed to make it
easy to continue scanning memory with minimal specifications each
time you use `x'.  For example, after you've inspected three machine
instructions with `x/3i ADDR', you can inspect the next seven with
just `x/7'.  If you use RET to repeat the `x' command, the repeat
count N is used again; the other arguments default as for successive
uses of `x'.

   The addresses and contents printed by the `x' command are not
saved in the value history because there is often too much of them
and they would get in the way.  Instead, GDB makes these values
available for subsequent use in expressions as values of the
convenience variables `$_' and `$__'.  After an `x' command, the
last address examined is available for use in expressions in the
convenience variable `$_'.  The contents of that address, as
examined, are available in the convenience variable `$__'.

   If the `x' command has a repeat count, the address and contents
saved are from the last memory unit printed; this is not the same as
the last address printed if several units were printed on the last
line of output.


File: gdb.info,  Node: Auto Display,  Next: Print Settings,  Prev: Memory,  Up: Data

Automatic Display
=================

   If you find that you want to print the value of an expression
frequently (to see how it changes), you might want to add it to the
"automatic
display list" so that GDB will print its value each time the program
stops.  Each expression added to the list is given a number to
identify it; to remove an expression from the list, you specify that
number.  The automatic display looks like this:

     2: foo = 38
     3: bar[5] = (struct hack *) 0x3804

showing item numbers, expressions and their current values.  As with
displays you request manually using `x' or `print', you can specify
the output format you prefer; in fact, `display' decides whether to
use `print' or `x' depending on how elaborate your format
specification
is--it uses `x' if you specify a unit size, or one of the two
formats (`i' and `s') that are only supported by `x'; otherwise it
uses `print'.

`display EXP'
     Add the expression EXP to the list of expressions to display
     each time the program stops.  *Note Expressions::.

     `display' will not repeat if you press RET again after using it.

`display/FMT EXP'
     For FMT specifying only a display format and not a size or
     count, add the expression EXP to the auto-display list but
     arranges to display it each time in the specified format FMT.
     *Note Output formats::.

`display/FMT ADDR'
     For FMT `i' or `s', or including a unit-size or a number of
     units, add the expression ADDR as a memory address to be
     examined each time the program stops.  Examining means in
     effect doing `x/FMT ADDR'.  *Note Memory::.

   For example, `display/i $pc' can be helpful, to see the machine
instruction about to be executed each time execution stops (`$pc' is
a common name for the program counter; *note Registers::.).

`undisplay DNUMS...'
`delete display DNUMS...'
     Remove item numbers DNUMS from the list of expressions to display.

     `undisplay' will not repeat if you press RET after using it.
     (Otherwise you would just get the error `No display number ...'.)

`disable display DNUMS...'
     Disable the display of item numbers DNUMS.  A disabled display
     item is not printed automatically, but is not forgotten.  It
     may be enabled again later.

`enable display DNUMS...'
     Enable display of item numbers DNUMS.  It becomes effective once
     again in auto display of its expression, until you specify
     otherwise.

`display'
     Display the current values of the expressions on the list, just
     as is done when the program stops.

`info display'
     Print the list of expressions previously set up to display
     automatically, each one with its item number, but without
     showing the values.  This includes disabled expressions, which
     are marked as such.  It also includes expressions which would
     not be displayed right now because they refer to automatic
     variables not currently available.

   If a display expression refers to local variables, then it does
not make sense outside the lexical context for which it was set up.
Such an expression is disabled when execution enters a context where
one of its variables is not defined.  For example, if you give the
command `display last_char' while inside a function with an argument
`last_char', then this argument will be displayed while the program
continues to stop inside that function.  When it stops
elsewhere--where there is no variable `last_char'--display is
disabled.  The next time your program stops where `last_char' is
meaningful, you can enable the display expression once again.


File: gdb.info,  Node: Print Settings,  Next: Value History,  Prev: Auto Display,  Up: Data

Print Settings
==============

   GDB provides the following ways to control how arrays, structures,
and symbols are printed.

These settings are useful for debugging programs in any language:

`set print address'
`set print address on'
     GDB will print memory addresses showing the location of stack
     traces, structure values, pointer values, breakpoints, and so
     forth, even when it also displays the contents of those
     addresses.  The default is on.  For example, this is what a
     stack frame display looks like, with `set print address on':

          (gdb) f
          #0  set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
              at input.c:530
          530         if (lquote != def_lquote)

`set print address off'
     Do not print addresses when displaying their contents.  For
     example, this is the same stack frame displayed with `set print
     address off':

          (gdb) set print addr off
          (gdb) f
          #0  set_quotes (lq="<<", rq=">>") at input.c:530
          530         if (lquote != def_lquote)

`show print address'
     Show whether or not addresses are to be printed.

`set print array'
`set print array on'
     GDB will pretty print arrays.  This format is more convenient to
     read, but uses more space.  The default is off.

`set print array off.'
     Return to compressed format for arrays.

`show print array'
     Show whether compressed or pretty format is selected for
     displaying arrays.

`set print elements NUMBER-OF-ELEMENTS'
     If GDB is printing a large array, it will stop printing after it
     has printed the number of elements set by the `set print
     elements' command.  This limit also applies to the display of
     strings.

`show print elements'
     Display the number of elements of a large array that GDB will
     print before losing patience.

`set print pretty on'
     Cause GDB to print structures in an indented format with one
     member per line, like this:

          $1 = {
            next = 0x0,
            flags = {
              sweet = 1,
              sour = 1
            },
            meat = 0x54 "Pork"
          }

`set print pretty off'
     Cause GDB to print structures in a compact format, like this:

          $1 = {next = 0x0, flags = {sweet = 1, sour = 1}, meat \
          = 0x54 "Pork"}

     This is the default format.

`show print pretty'
     Show which format GDB will use to print structures.

`set print sevenbit-strings on'
     Print using only seven-bit characters; if this option is set,
     GDB will display any eight-bit characters (in strings or
     character values) using the notation `\'NNN.  For example,
     `M-a' is displayed as `\341'.

`set print sevenbit-strings off'
     Print using either seven-bit or eight-bit characters, as
     required.  This is the default.

`show print sevenbit-strings'
     Show whether or not GDB will print only seven-bit characters.

`set print union on'
     Tell GDB to print unions which are contained in structures.
     This is the default setting.

`set print union off'
     Tell GDB not to print unions which are contained in structures.

`show print union'
     Ask GDB whether or not it will print unions which are contained
     in structures.

     For example, given the declarations

          typedef enum {Tree, Bug} Species;
          typedef enum {Big_tree, Acorn, Seedling} Tree_forms;
          typedef enum {Caterpillar, Cocoon, Butterfly} Bug_forms;

          struct thing {
            Species it;
            union {
              Tree_forms tree;
              Bug_forms bug;
            } form;
          };

          struct thing foo = {Tree, {Acorn}};

     with `set print union on' in effect `p foo' would print

          $1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}}

     and with `set print union off' in effect it would print

          $1 = {it = Tree, form = {...}}

These settings are of interest when debugging C++ programs:

`set print demangle'
`set print demangle on'
     Print C++ names in their source form rather than in the mangled
     form in which they are passed to the assembler and linker for
     type-safe linkage.  The default is on.

`show print demangle'
     Show whether C++ names will be printed in mangled or demangled
     form.

`set print asm-demangle'
`set print asm-demangle on'
     Print C++ names in their source form rather than their mangled
     form, even in assembler code printouts such as instruction
     disassemblies.  The default is off.

`show print asm-demangle'
     Show whether C++ names in assembly listings will be printed in
     mangled or demangled form.

`set print object'
`set print object on'
     When displaying a pointer to an object, identify the *actual*
     (derived) type of the object rather than the *declared* type,
     using the virtual function table.

`set print object off'
     Display only the declared type of objects, without reference to
     the virtual function table.  This is the default setting.

`show print object'
     Show whether actual, or declared, object types will be displayed.

`set print vtbl'
`set print vtbl on'
     Pretty print C++ virtual function tables.  The default is off.

`set print vtbl off'
     Do not pretty print C++ virtual function tables.

`show print vtbl'
     Show whether C++ virtual function tables are pretty printed, or
     not.


File: gdb.info,  Node: Value History,  Next: Convenience Vars,  Prev: Print Settings,  Up: Data

Value History
=============

   Values printed by the `print' command are saved in GDB's "value
history" so that you can refer to them in other expressions.  Values
are kept until the symbol table is re-read or discarded (for example
with the `file' or `symbol-file' commands).  When the symbol table
changes, the value history is discarded, since the values may
contain pointers back to the types defined in the symbol table.

   The values printed are given "history numbers" for you to refer to
them by.  These are successive integers starting with one.  `print'
shows you the history number assigned to a value by printing `$NUM =
' before the value; here NUM is the history number.

   To refer to any previous value, use `$' followed by the value's
history number.  The way `print' labels its output is designed to
remind
you of this.  Just `$' refers to the most recent value in the
history, and `$$' refers to the value before that.  `$$N' refers to
the Nth value from the end; `$$2' is the value just prior to `$$',
`$$1' is equivalent to `$$', and `$$0' is equivalent to `$'.

   For example, suppose you have just printed a pointer to a
structure and want to see the contents of the structure.  It
suffices to type

     p *$

   If you have a chain of structures where the component `next'
points to the next one, you can print the contents of the next one
with this:

     p *$.next

You can print successive links in the chain by repeating this
command--which you can do by just typing RET.

   Note that the history records values, not expressions.  If the
value of `x' is 4 and you type these commands:

     print x
     set x=5

then the value recorded in the value history by the `print' command
remains 4 even though the value of `x' has changed.

`show values'
     Print the last ten values in the value history, with their item
     numbers.  This is like `p $$9' repeated ten times, except that
     `show values' does not change the history.

`show values N'
     Print ten history values centered on history item number N.

`show values +'
     Print ten history values just after the values last printed.  If
     no more values are available, produces no display.

   Pressing RET to repeat `show values N' has exactly the same effect
as `show values +'.


File: gdb.info,  Node: Convenience Vars,  Next: Registers,  Prev: Value History,  Up: Data

Convenience Variables
=====================

   GDB provides "convenience variables" that you can use within GDB
to hold on to a value and refer to it later.  These variables exist
entirely within GDB; they are not part of your program, and setting
a convenience variable has no direct effect on further execution of
your program.  That's why you can use them freely.

   Convenience variables are prefixed with `$'.  Any name preceded by
`$' can be used for a convenience variable, unless it is one of the
predefined machine-specific register names (*note Registers::.).
(Value history references, in contrast, are *numbers* preceded by
`$'.  *Note Value History::.)

   You can save a value in a convenience variable with an assignment
expression, just as you would set a variable in your program.
Example:

     set $foo = *object_ptr

would save in `$foo' the value contained in the object pointed to by
`object_ptr'.

   Using a convenience variable for the first time creates it; but
its value is `void' until you assign a new value.  You can alter the
value with another assignment at any time.

   Convenience variables have no fixed types.  You can assign a
convenience variable any type of value, including structures and
arrays, even if that variable already has a value of a different
type.  The convenience variable, when used as an expression, has the
type of its current value.

`show convenience'
     Print a list of convenience variables used so far, and their
     values.  Abbreviated `show con'.

   One of the ways to use a convenience variable is as a counter to
be incremented or a pointer to be advanced.  For example, to print a
field from successive elements of an array of structures:

     set $i = 0
     print bar[$i++]->contents
     ... repeat that command by typing RET.

   Some convenience variables are created automatically by GDB and
given values likely to be useful.

`$_'
     The variable `$_' is automatically set by the `x' command to the
     last address examined (*note Memory::.).  Other commands which
     provide a default address for `x' to examine also set `$_' to
     that address; these commands include `info line' and `info
     breakpoint'.  The type of `$_' is `void *' except when set by
     the `x' command, in which case it is a pointer to the type of

     `$__'.

`$__'
     The variable `$__' is automatically set by the `x' command to
     the value found in the last address examined.  Its type is
     chosen to match the format in which the data was printed.


File: gdb.info,  Node: Registers,  Next: Floating Point Hardware,  Prev: Convenience Vars,  Up: Data

Registers
=========

   You can refer to machine register contents, in expressions, as
variables with names starting with `$'.  The names of registers are
different for each machine; use `info registers' to see the names
used
on your machine.

`info registers'
     Print the names and values of all registers except
     floating-point registers (in the selected stack frame).

`info all-registers'
     Print the names and values of all registers, including
     floating-point registers.

`info registers REGNAME'
     Print the relativized value of register REGNAME.  REGNAME may be
     any register name valid on the machine you are using, with or
     without the initial `$'.

   GDB has four "standard" register names that are available (in
expressions) on most machines--whenever they don't conflict with an
architecture's canonical mnemonics for registers.  The register
names `$pc' and `$sp' are used for the program counter register and
the stack pointer.  `$fp' is used for a register that contains a
pointer
to the current stack frame, and `$ps' is used for a register that
contains the processor status.  For example, you could print the
program counter in hex with

     p/x $pc

or print the instruction to be executed next with

     x/i $pc

or add four to the stack pointer (1) with

     set $sp += 4

   Whenever possible, these four standard register names are
available on your machine even though the machine has different
canonical mnemonics, so long as there is no conflict.  The `info
registers' command shows the canonical names.  For example, on the
SPARC, `info registers' displays the processor status register as
`$psr' but you can also refer to it as `$ps'.

   GDB always considers the contents of an ordinary register as an
integer when the register is examined in this way.  Some machines
have special registers which can hold nothing but floating point;
these registers are considered to have floating point values.  There
is no way to refer to the contents of an ordinary register as
floating point value (although you can *print* it as a floating
point value with `print/f $REGNAME').

   Some registers have distinct "raw" and "virtual" data formats.
This means that the data format in which the register contents are
saved by the operating system is not the same one that your program
normally sees.  For example, the registers of the 68881 floating
point coprocessor are always saved in "extended" (raw) format, but
all C programs expect to work with "double" (virtual) format.  In
such cases, GDB normally works with the virtual format only (the
format that makes sense for your program), but the `info registers'
command prints the data in both formats.

   Normally, register values are relative to the selected stack frame
(*note Selection::.).  This means that you get the value that the
register would contain if all stack frames farther in were exited
and their saved registers restored.  In order to see the true
contents of hardware registers, you must select the innermost frame
(with `frame 0').

   However, GDB must deduce where registers are saved, from the
machine code generated by your compiler.  If some registers are not
saved, or if GDB is unable to locate the saved registers, the
selected stack frame will make no difference.

   ---------- Footnotes ----------

   (1)  This is a way of removing one word from the stack, on
machines where stacks grow downward in memory (most machines,
nowadays).  This assumes that the innermost stack frame is selected;
setting `$sp' is not allowed when other stack frames are selected.
To
pop entire frames off the stack, regardless of machine architecture,
use `return'; *note Returning::..


File: gdb.info,  Node: Floating Point Hardware,  Prev: Registers,  Up: Data

Floating Point Hardware
=======================

   Depending on the host machine architecture, GDB may be able to
give you more information about the status of the floating point
hardware.

`info float'
     If available, provides hardware-dependent information about the
     floating point unit.  The exact contents and layout vary
     depending on the floating point chip.


File: gdb.info,  Node: Languages,  Next: Symbols,  Prev: Data,  Up: Top

Using GDB with Different Languages
**********************************

   Although programming languages generally have common aspects, they
are rarely expressed in the same manner.  For instance, in ANSI C,
dereferencing a pointer `p' is accomplished by `*p', but in
Modula-2, it is accomplished by `p^'.  Values can also be
represented (and displayed) differently.  Hex numbers in C are
written like `0x1ae', while in Modula-2 they appear as `1AEH'.

   Language-specific information is built into GDB for some
languages, allowing you to express operations like the above in the
program's native language, and allowing GDB to output values in a
manner consistent with the syntax of the program's native language.
The language you use to build expressions, called the "working
language", can be selected manually, or GDB can set it automatically.

* Menu:

* Setting::                     Switching between source languages
* Show::                        Displaying the language
* Checks::                      Type and Range checks
* Support::                     Supported languages


File: gdb.info,  Node: Setting,  Next: Show,  Prev: Languages,  Up: Languages

Switching between source languages
==================================

   There are two ways to control the working language--either have
GDB set it automatically, or select it manually yourself.  You can
use the `set language' command for either purpose.  On startup, GDB
defaults to setting the language automatically.

* Menu:

* Manually::                    Setting the working language manually
* Automatically::               Having GDB infer the source language


File: gdb.info,  Node: Manually,  Next: Automatically,  Prev: Setting,  Up: Setting

Setting the working language
----------------------------

   To set the language, issue the command `set language LANG', where
LANG is the name of a language: `c' or `modula-2'.  For a list of
the supported languages, type `set language'.

   Setting the language manually prevents GDB from updating the
working language automatically.  This can lead to confusion if you
try to debug a program when the working language is not the same as
the
source language, when an expression is acceptable to both
languages--but means different things.  For instance, if the current
source file were written in C, and GDB was parsing Modula-2, a
command such as:

     print a = b + c

might not have the effect you intended.  In C, this means to add `b'
and `c' and place the result in `a'.  The result printed would be
the value of `a'.  In Modula-2, this means to compare `a' to the
result of `b+c', yielding a `BOOLEAN' value.

   If you allow GDB to set the language automatically, then you can
count on expressions evaluating the same way in your debugging
session and in your program.


File: gdb.info,  Node: Automatically,  Prev: Manually,  Up: Setting

Having GDB infer the source language
------------------------------------

   To have GDB set the working language automatically, use `set
language local' or `set language auto'.  GDB then infers the
language that a program was written in by looking at the name of its
source files, and examining their extensions:

`*.mod'
     Modula-2 source file

`*.c'
`*.cc'
     C or C++ source file.

   This information is recorded for each function or procedure in a
source file.  When your program stops in a frame (usually by
encountering a breakpoint), GDB sets the working language to the
language recorded for the function in that frame.  If the language
for a frame is unknown (that is, if the function or block
corresponding to the frame was defined in a source file that does
not have a recognized extension), the current working language is
not changed, and GDB issues a warning.

   This may not seem necessary for most programs, which are written
entirely in one source language.  However, program modules and
libraries written in one source language can be used by a main
program written in a different source language.  Using `set language
auto' in this case frees you from having to set the working language
manually.


File: gdb.info,  Node: Show,  Next: Checks,  Prev: Setting,  Up: Languages

Displaying the language
=======================

   The following commands will help you find out which language is
the working language, and also what language source files were
written in.

`show language'
     Display the current working language.  This is the language you
     can use with commands such as `print' to build and compute
     expressions that may involve variables in the program.

`info frame'
     Among the other information listed here (*note Information about
     a Frame: Frame Info.) is the source language for this frame.
     This is the language that will become the working language if
     you ever use an identifier that is in this frame.

`info source'
     Among the other information listed here (*note Examining the
     Symbol Table: Symbols.) is the source language of this source
     file.


File: gdb.info,  Node: Checks,  Next: Support,  Prev: Show,  Up: Languages

Type and range Checking
=======================

     *Warning:* In this release, the GDB commands for type and range

     checking are included, but they do not yet have any effect.
     This section documents the intended facilities.

   Some languages are designed to guard you against making seemingly
common errors through a series of compile- and run-time checks.
These
include checking the type of arguments to functions and operators,
and making sure mathematical overflows are caught at run time.
Checks such as these help to ensure a program's correctness once it
has
been compiled by eliminating type mismatches, and providing active
checks for range errors when the program is running.

   GDB can check for conditions like the above if you wish.  Although
GDB will not check the statements in your program, it can check
expressions entered directly into GDB for evaluation via the `print'
command, for example.  As with the working language, GDB can also
decide whether or not to check automatically based on the source
language of the program being debugged.  *Note Supported Languages:
Support, for the default settings of supported languages.

* Menu:

* Type Checking::               An overview of type checking
* Range Checking::              An overview of range checking